home *** CD-ROM | disk | FTP | other *** search
/ Software 2000 / Software 2000 Volume 1 (Disc 1 of 2).iso / utilities / u135.dms / in.adf / Powerpacker / POWERPACKER.DOC < prev    next >
Encoding:
Text File  |  2000-10-30  |  20.1 KB  |  565 lines
  1.  
  2.  
  3.                 Power Packer V2.1b User Manual
  4.  
  5.                         March 21, 1989
  6.  
  7.  
  8.  
  9. Preface
  10. =======
  11.  
  12. Congratulations, you have just obtained a copy of Power 
  13. Peak's new and improved PowerPacker 2.1b.  If you have 
  14. suggestions or remarks about this program, or if you find
  15. any bugs, please let me know.
  16.  
  17. This version of the PowerPacker is shareware, this means
  18. that if you use it a lot I would appreciate it if you'd 
  19. send me a contribution of $10 or the same amount in any 
  20. other currency.This money will enable me to produce more 
  21. programs on the Amiga.  If you send $15 I will send you 
  22. the latest version of the PowerPacker.
  23.      
  24. Write to the following address:
  25.  
  26.                                 Franois Nico
  27.                                 Corbielaan 13
  28.                              3060 Bertem BELGIUM
  29.  
  30.  
  31. Contents
  32. ========
  33.  
  34. 1. The Packer
  35.      1.1 An introduction
  36.      1.2 The file requester
  37.      1.3 The basic menus
  38.           1.3.1 Project
  39.           1.3.2 Prefs
  40.  
  41. 2. Recrunch
  42.      2.1 How ?
  43.      2.2 Why ?
  44.  
  45. 3. The HunkLab
  46.      3.1 Preferences
  47.      3.2 Process file
  48.  
  49. 4. The Script Menu
  50.  
  51. 5. The Supervisor Window
  52.  
  53. 6. A Sample Session
  54.  
  55. 7. PowerPacker 2.1b & the CLI
  56.  
  57.  
  58. 1. The Packer
  59. -------------
  60.  
  61. 1.1 An introduction
  62.  
  63. The PowerPacker is a userfriendly command and data 
  64. cruncher, this means a menu driven utility that can crunch
  65. almost any file on your disks.  When you use it for the 
  66. first time it's best to maintain a certain order in your 
  67. actions (as we will see in chapter 6 of this document):
  68.  
  69.   (a) set the packer options at the beginning of a session
  70.       (Prefs menu)
  71.   (b) load the file from disk (Project menu)
  72.   (c) save the file back to disk (Project menu)
  73.  
  74. Apart from the crunching, you can also recrunch files that 
  75. were crunched by some other crunchers.
  76. The HunkLab enables you to e.g. force code or data in chip
  77. ram The script, a new feature in 2.1b, allows you to e.g. 
  78. crunch a dozen of files overnight.
  79.  
  80. Before I demonstrate how to use the PowerPacker, let's 
  81. look at the file requester and a brief overview of the 
  82. menus and capabilities.
  83.  
  84.  
  85. 1.2 The file requester
  86.  
  87. Whenever you are required to enter a filename, the packer 
  88. sets up a file requester.  This requester automatically 
  89. contains all devices connected to your Amiga and lists all
  90. the files (and their length) of a selected directory.  
  91. You don't have to wait for the directory read to end.  
  92. You can select a file or directory the moment you see it,
  93. or you can enter it in the appropriate string gadget.
  94.  
  95. However, if you wait for the directory read to end and quit 
  96. the file requester, the next time you use it all the files 
  97. will still be there, so you don't have to wait for the 
  98. directory to be read again (This is very useful when you 
  99. are recording a script, as you'll see later).  This feature
  100. has one disadvantage :  if files are changed or added to 
  101. the selected directory they won't be shown in the list, or
  102. they  will be shown with the wrong filelength, the next 
  103. time the requester appears.  Therefore, if you think 
  104. anything has been changed to the selected directory, use 
  105. the 'GET DIR' gadget to re-read the directory.  (E.g. 
  106. when you save a crunched file on top of the old one, the 
  107. old file length will be shown in the requester.)
  108.  
  109.  
  110. 1.3 The basic menus
  111.  
  112. 1.3.1 Project
  113.  
  114. The project menu contains the file manipulation options. 
  115. Most of them speak for themselves:
  116.  
  117.   Load      ->  Load a file from disk and start the (de)
  118.                 crunching.
  119.   Save      ->  Save the (de)crunched or processed file in
  120.                 memory to disk.
  121.   Delete    ->  Delete a file from disk.
  122.   WorkBench ->  Open or close WorkBench if possible. (Adds
  123.                  42K !)
  124.   About...  ->  Show general information and my address.
  125.   Quit      ->  Quit the program.
  126.  
  127. 1.3.2 Prefs
  128.  
  129.      The prefs menu contains all the (de)cruncher settings.
  130.      You can select to (de)crunch command files or a data 
  131.      files.  If you want the crunched version of your file
  132.      to  be executable, select 'Command file'. Now the 
  133.      PowerPacker knows it has to add a decrunch header 
  134.      (572 bytes).  If the file you want to crunch only 
  135.      contains data (e.g. Source codes of your own programs)
  136.      select the 'Data file' option.  This can be handy if 
  137.      you're going to use the PowerPacker CLI commands.   
  138.      I'll discuss these commands in chapter 5 of this 
  139.      document.  Finally you have to choose whether you want
  140.      to crunch or decrunch the load file.
  141.  
  142. Note: - The PowerPacker will automatically decrunch a 
  143.         previously crunched file.  You don't have to select
  144.         crunch or decrunch mode anymore as in PowerPacker 
  145.         2.0a.
  146.  
  147.      The 'Decrunch Color' submenu contains the following 
  148.      options :
  149.  
  150.   Color 0   ->  The background color will change while 
  151.                 decrunching
  152.   Color 1   ->  The text color changes
  153.   Pointer   ->  Only the mousepointer's color changes
  154.   Scroll    ->  Handy for decrunching a demo 
  155.                 (just try it out !)
  156.   None      ->  If you're eyes are wearing out.
  157.  
  158. These options indicate what color will flash when a file is 
  159. decrunched. You can change this option before saving a 
  160. crunched file, so you can save a version of your crunched 
  161. program that flashes in color 1, and one that flashes in 
  162. the mouse pointer.
  163. If the 'Color Crunch' option is selected, the PowerPacker 
  164. will use the same color while crunching the file, giving 
  165. you an idea what the decrunching will look like (provided 
  166. that you don't change any options just before saving to 
  167. disk). The default value is color 1.
  168.  
  169. In the efficiency submenu you will find the following 
  170. possibilities :
  171.  
  172.   Fast      ->  Use for small files, or for quick crunch.
  173.   Mediocre  ->  Better but slower.
  174.   Good      ->  Default, gains 40-50% in most cases.
  175.   Very Good ->  Also very slow !
  176.   Best      ->  Advised for script use only, ultra slow !!!
  177.  
  178. Note: - 'Fast' is approx. 4 times faster than 'Good',
  179.         'Very Good' is 2 times slower and 'Best' 4 times.
  180.  
  181. You can set Amiga's multitasking off to increase the 
  182. crunching speed.  The default setting is on.  When you want 
  183. to use the PowerPacker in a multitasking environment, you'll 
  184. probably start a crunching job and at the same time continue 
  185. your work.  In that case, it might be interesting to set the 
  186. 'LED Crunch' option on.  Now your power-LED flashes while 
  187. crunching,just like the screencolors. 
  188. (but I presume they're already turned off because editing a
  189. file with flashing text really gets on your nerves)
  190. You can even turn off your monitor and still see when the 
  191. cruncher has finished.
  192.  
  193. Finally, you can set the paging in the supervisor window on 
  194. so you can read the crunch and hunk information, without 
  195. everything racing off the screen before you've had a chance 
  196. to see it.
  197.  
  198. Note: - While crunching, you can press both mousebuttons at 
  199. the same time to abort.
  200. - Do *NOT* change disks when you are crunching with the 
  201. multitasking switched off !!!  The Amiga will crash !!!
  202.  
  203. 2. Recrunch
  204. -----------
  205.  
  206. 2.1 How ?
  207.  
  208.      This menu is provided for the people who were using
  209. another cruncher or an older version of the PowerPacker.
  210. Just select 'Recrunch File' or 'Decrunch Only' and load the 
  211. file.  The PowerPacker will start the correct decrunch 
  212. algorithm.  If you selected 'Recrunch' the PowerPacker will
  213. start to crunch the decrunched file.  If the PowerPacker 
  214. doesn't recognize the cruncher it will say so, no harm is 
  215. done.  If you select 'Recrunch Always' the PowerPacker will 
  216. always recrunch, even if the file was crunched with this
  217. version of the PowerPacker.  Useful for recrunching files 
  218. using a higher efficiency. (E.g. recrunch a 'Fast' crunched 
  219. file in 'Best')
  220.  
  221.      Crunchers currently supported are: 'ANC Cruncher' 'TNM
  222.  Cruncher 1.1','Relokit 1.0' and older PowerPacker files. 
  223. If you'd like to see other crunchers supported, send me the 
  224. cruncher and some programs crunched with it. 
  225. (With a contribution I hope).  If it is possible to develop
  226. a decrunch algorithm I will include it in the next version 
  227. of the PowerPacker.
  228.  
  229. 2.2 Why ?
  230.  
  231.      The PowerPacker always crunches better than the 'ANC 
  232. Cruncher' and the 'TNM Cruncher'.  It crunches better than 
  233. 'Relokit' most of the time, but even if it doesn't, I 
  234. advise you to recrunch because 'Relokit' has some serious 
  235. disadvantages (e.g. while the decrunched file is running,
  236. the crunched version still eats memory).  In contrast the 
  237. PowerPacker only eats about 580 bytes while your file is 
  238. running, and (of course) frees it afterwards.
  239.  
  240. Note: - If you want to recrunch a PowerPacker 1.1 or 2.0 
  241. crunched file, the PowerPacker just replaces the file 
  242. header with the improved and debugged 2.1 header. (Unless
  243. you've selected 'Recrunch Always')
  244.  - The recrunch menu only supports command files !  You
  245. can't recrunch data files from e.g. PowerPacker 1.0, sorry
  246.  
  247. 2. The Hunklab
  248. --------------
  249.  
  250. 2.1 Preferences
  251.  
  252.      This menu is not really part of the PowerPacker 
  253. crunch/decrunch routines but it wasn't worth writing a 
  254. separate program for and a HunkLab is after all a very 
  255. interesting utility.  You can e.g. use it to remove symbol
  256. and debug hunks from files that wouldn't crunch otherwise.
  257.  
  258. You can force a program's code, data or BSS (uninitialised 
  259. data) into chip ram or you can remove symbol tables and 
  260. debug information just by toggling the marker on/off.  
  261. So in future,when you want your programs to be able to run
  262. on a one megabyte system, a simple click on the 
  263. mousebutton will do.
  264.  
  265. 2.2 Process file
  266.  
  267.      'Process file' reads the file from disk and changes 
  268. it according to your preferences.  To save the processed 
  269. file, use 'Save' from the Project menu. 'Process & Crunch'
  270. will process the file and crunch the file afterwards 
  271. (if possible). To save use 'Save' in the Project menu.
  272.  
  273.  
  274. 3. The Script Menu
  275. ------------------
  276.  
  277.      This menu is a new feature in version 2.1b. It allows 
  278. you to record 80 different commands to be executed after
  279. each other.  It is ideal for crunching a lot of files 
  280. overnight. 
  281.  
  282. Menu options are:
  283.  
  284.      'Clear Script' and 'List Script' will do just that.
  285.      'Script Log File' is used to specify a file to 
  286.       redirect output to.  If you cancel the requester no
  287.       log file is  used.
  288.      'Destination Dir' is used to specify the directory to 
  289.       save to.  It is ghosted in the normal use.
  290.      'Start Recording' is used to start the recording of 
  291.       the script. If the script was empty you will be 
  292.       asked for the destination directory.
  293.       You will also be asked whether to append '.pp21' to
  294.       the destination file.  You're advised to do this for
  295.       data  files.
  296.       After selecting the destination you can start 
  297.       entering the script commands.  Everything that is 
  298.       ghosted is not available as a command.  Just enter 
  299.       everything as if you were actually using the 
  300.       PowerPacker.  When you e.g. choose 'Load' the 
  301.       PowerPacker will ask a list of files to be 
  302.       (de)crunched. Press 'CANCEL' to exit the entry.
  303.       Note: - You can still change the source and 
  304.       destination dir while recording.
  305.       Every command you enter will be displayed in the 
  306.       supervisor window. 'Stop Recording' is used to exit
  307.       the recording mode.'Delete Last' will delete the 
  308.       last command after a confirmation. 'Execute Script'
  309.       finally, is used to start the playback of the script 
  310.       commands.  
  311.       If you press the menu button a requester will appear
  312.       to ask you if you want to abort the script execution.
  313.       After executing the script a request to clear the 
  314.       script will appear.
  315.  
  316. Note: - It is advisable to let the filerequester buffer 
  317.         fill before you start selecting files.  It is also 
  318.         better not to change the source directory too often.
  319.       - The screen turns grey to indicate a script is 
  320.         executing.
  321.       - While executing a script, the PowerPacker will 
  322.         always act destructive !  Files will allways be 
  323.         overwritten and deleted !!!
  324.  
  325. 4. The Supervisor Window
  326. ------------------------
  327.  
  328.      This window displays all kind of useful information 
  329. like the file status, crunch messages, and error messages.
  330. You can follow all steps, from the original file that is 
  331. loaded into memory, to the final crunched version on disk.
  332. When an executable file is loaded, its hunk information is
  333. displayed. This information is rather technical, but it 
  334. can be useful for programmers.  If you're not interested,
  335. just ignore it.
  336.  
  337. I think it might be useful to give a list of possible 
  338. error messages:
  339.  
  340. (De)crunch : Buffer overflow !
  341.               (Crunched file is getting longer than 
  342.               original file)
  343.              Crunch aborted !
  344.               (Crunching stopped by user or by buffer 
  345.               overflow)
  346.              No memory for decrunch buffer !
  347.              Out of memory !
  348.                (Buy some more, or try closing the 
  349.                 WorkBench)
  350.              Sorry, can't crunch !
  351.                (This is a polite program)
  352.              Can't find hunk_header.
  353.              Hunk not allowed in load file!
  354.              Unknown Hunk !
  355.                (Not a command file)
  356.              Hunk not supported (yet ?) !
  357.                (If it's a symbol or debug hunk, try 
  358.                removing it in HunkLab)
  359.              Nothing to save !
  360.                (Buffer is empty)
  361.              Save Aborted !
  362.              Error reading file !
  363.              Can't open file !
  364.              Error writing data header !
  365.              Error writing buffer !
  366.              File not found !
  367.              Couldn't delete file !
  368.              Can't open file !
  369.                 (Disk errors)
  370.  
  371. Recrunch :    No need to recrunch 'PowerPacker 1.1' command
  372.               file, Replacing 1.1 decrunch header with 2.1
  373.               header...
  374.               (2.1 header is shorter and bugfree,1.1 isn't)
  375.               No need to recrunch 'PowerPacker 2.0' command
  376.               file,Replacing 2.0 decrunch header with 2.1
  377.               header...(There was still a small bug in 2.0
  378.               header, so replace it.) Not crunched with one
  379.               of the supported crunchers !!
  380.               (Or file is not crunched at all !)
  381.               Sorry, can't recrunch !
  382.               (We're always polite)
  383.  
  384. Process :     Sorry, can't process file !
  385.                 (File is probably not a command file)
  386.               Can't crunch file !
  387.                 (File still contains unsupported hunks)
  388.  
  389. Script :      Script buffer full !! Please stop recording.
  390.                 (Script is limited to 80 commands, choose 
  391.                'Stop Recording')
  392.  
  393. 5. A Sample Session
  394. -------------------
  395.  
  396. Now that I have explained the PowerPacker's capabilities,
  397. it's time for a little demonstation.  Let's say we want to
  398. crunch the 'CLI' command in the System directory on your 
  399. Workbench 1.2 disk.
  400.  
  401. Select 'Pointer' in the Prefs/Decrunch Color menu (When
  402. I wrote this text, it was very late and I couldn't stand 
  403. the other decrunch colors anymore !)
  404.  
  405. Set 'Prefs' to 'Command file'.  Now select 'Load' in the
  406. Project menu (a file requester will appear), insert your 
  407. WorkBench 1.2 disk and choose the 'CLI' command in the 
  408. system directory.  Now you'll see a lot of hunk 
  409. information about the CLI command:
  410.  
  411.                                                                              
  412.      Loading command file 'df0:System/CLI'...        
  413.                                                         
  414.      Hunk_header (0x03F3)                  
  415.      9 hunks (0 to 8).                    
  416.      Hunk  0 : Hunk_code (0x03E9)     (524 bytes) 
  417.                Hunk_reloc32 (0x03EC)           
  418.      Hunk  1 : Hunk_data (0x03EA)   (428 bytes, 0 BSS)
  419.      Hunk  2 : Hunk_code (0x03E9)   (472 bytes) 
  420.                Hunk_reloc32 (0x03EC)  
  421.      Hunk  3 : Hunk_data (0x03EA)   (52 bytes, 0 BSS)
  422.      Hunk  4 : Hunk_code (0x03E9)   (16 bytes)
  423.      Hunk  5 : Hunk_code (0x03E9)   (0 bytes)
  424.      Hunk  6 : Hunk_code (0x03E9)   (196 bytes)
  425.                Hunk_reloc32 (0x03EC)
  426.      Hunk  7 : Hunk_code (0x03E9)      
  427.                Hunk_reloc32 (0x03EC)                 
  428.      Hunk  8 : Hunk_data (0x03EA)   (0 bytes, 0 BSS) 
  429.                                   
  430.                Crunching command file...                                                  
  431.                Press left and right button to abort.                                  
  432.                Crunching, please wait.                                                 
  433.  
  434.  
  435. The cruncher displays the percentage of the file already 
  436. crunched and after some time your screen will look like
  437. this:
  438.                                                                              
  439.     100% crunched.                                                          
  440.     Done.                                                                   
  441.     Original length : 2356 bytes.                                          
  442.     Crunched length : 1204 (1776) bytes.                                    
  443.     Gained 49% (1152 bytes) !                                               
  444.  
  445.  
  446.    The only thing you have to do now is save this back to
  447.    disk as an executable file.  Now enjoy the crunched CLI 
  448.    command.
  449.  
  450.  
  451. 6. PowerPacker 2.1b & the CLI
  452. -----------------------------
  453.  
  454. For your convenience, I have also written two CLI commands, 
  455. one to crunch and one to decrunch. Attention:  These 
  456. commands only (de)crunch DATA files !!!!  (So to crunch 
  457. executable files, you'll still have to use the PowerPacker
  458.  2.1b). A usage line is given by typing 'Crunch' or 
  459. 'Decrunch' without arguments.  You'll get something like
  460.  this:
  461.  
  462. 1>
  463. 1> crunch
  464. POWER-PACKER 2.1a Data Cruncher.
  465. Written by Lone Wolf from POWERPEAK.
  466. USAGE : Crunch <source> <destination> [efficiency (1-5) 
  467.         default 3] [P] [F]
  468.         Where P stands for no percentage,
  469.          F for Forbid() crunching.
  470. 1>
  471. 1> decrunch
  472. POWER-PACKER 2.1a Data Decruncher.
  473. Written by Lone Wolf from POWERPEAK.
  474. USAGE : Decrunch <source> <destination> [decrunch color 
  475. (0-4)] With decrunch color 0/1 -> Color 0/1, 2 -> 
  476. Pointer, 3 -> Scroll, 4 -> None If <destination> is a *
  477. the file will be typed to Output().
  478.  
  479. 1>
  480.  
  481. These commands are useful to be included in your 
  482. startup-sequence or to read crunched text files quickly.
  483.  
  484. I don't think these commands need any further explanation. 
  485. Just try them out and you'll see what happens.  
  486. E.g. when you have a crunched source file of a program on 
  487. your disk, typing
  488.  
  489.      Decrunch filename.c *
  490.  
  491. will display the file as if you were using the 'Type' 
  492. command for textfiles.
  493.  
  494.                                                 Enjoy !!!
  495.  
  496.  
  497.                      PROGRAM HISTORY:
  498.  
  499. *********************************************************
  500. VERSION 1.0a
  501.  
  502.      First release.
  503.  
  504. *********************************************************
  505. VERSION 1.1a
  506.  
  507.      Fixed bugs.
  508.      Improved crunch algorithm by about 5%.
  509.      'Delete' and 'Multitask' added.
  510.      Better menu structure.
  511.      Improved the file requester.
  512.      Written CLI commands.
  513.  
  514. *********************************************************
  515. VERSION 2.0a
  516.  
  517.      Fixed some more bugs.
  518.      Added buffer and automatic device-list to the file
  519.      requester. Added 'LED Crunch', useful for turning the
  520.      monitor off while crunching, and 'Paging'.
  521.      New header, bug fixed. (1.1 didn't free mem when 
  522.      started from WorkBench) Added the hunklab.Improved 
  523.      CLI commands.
  524.  
  525. *********************************************************
  526. VERSION 2.1a
  527.  
  528.      Fixed last bug in header (2.0 crashed when you were 
  529.      out of mem) Added script feature, now possible to 
  530.      crunch files overnight.
  531.      Improved requesters.
  532.      Automatic crunch/decrunch.
  533.      Improved menu structure considerably.
  534.      Intelligent recrunch implemented.
  535.      Automatic crunch/decrunch.
  536.      Added 'Color Crunch' option.
  537.      New efficiency 'Best' added.
  538.  
  539. **********************************************************
  540. VERSION 2.1b
  541.  
  542.      Bug fixed in script abort.
  543.      Added ability to open a log file during script 
  544.      execute. Now possible to recrunch PowerPacker files 
  545.      with a higher efficiency.
  546.      Recrunch detects unsupported crunchers a lot faster.
  547.      Version supposed to work on NTSC Amiga (not tested !)
  548.  
  549. **********************************************************
  550.  
  551.  
  552. P.S. This text file crunched to 42% of it's original 
  553. length. (Gained 58% !)
  554.  
  555. The PowerPacker 2.1b written by François Nico (Lone Wolf).
  556. Special thanks to Pauwels Luc (Red Eagle) for writing the
  557. 2.0a manual and Tybergein Jorrit (Edain) for the extensive
  558. debugging.
  559.  
  560. (c) 1989 François Nico / Power Peak
  561.  
  562.                //
  563.    Thanks to \X/ Amiga for being the best computer ever !
  564.  
  565.